[English]

LED 控制器 (LEDC) 主要用于控制 LED，也可产生 PWM 信号用于其他设备的控制。 该控制器有 16 路通道，可以产生独立的波形来驱动 RGB LED 等设备。

LEDC 通道共有两组，分别为 8 路高速通道和 8 路低速通道。高速通道模式在硬件中实现，可以自动且无干扰地改变 PWM 占空比。低速通道模式下，PWM 占空比需要由软件中的驱动器改变。每组通道都可以使用不同的时钟源。

LED PWM 控制器可在无需 CPU 干预的情况下自动改变占空比，实现亮度和颜色渐变。

设置 LEDC 通道在 高速模式或低速模式 下运行，需要进行如下配置：

定时器配置 指定 PWM 信号的频率和占空比分辨率。

通道配置 绑定定时器和输出 PWM 信号的 GPIO。

改变 PWM 信号 输出 PWM 信号来驱动 LED。可通过软件控制或使用硬件渐变功能来改变 LED 的亮度。

另一个可选步骤是可以在渐变终端设置一个中断。

LED PWM 控制器 API 的关键配置¶

要设置定时器，可调用函数 ledc_timer_config()，并将包括如下配置参数的数据结构 ledc_timer_config_t 传递给该函数：

速度模式 ledc_mode_t

定时器索引 ledc_timer_t

PWM 信号频率

PWM 占空比分辨率

频率和占空比分辨率相互关联。PWM 频率越高，占空比分辨率越低，反之亦然。如果 API 不是用来改变 LED 亮度，而是用于其它目的，这种相互关系可能会很重要。更多信息详见 频率和占空比分辨率支持范围 一节。

定时器设置好后，请配置所需的通道（ledc_channel_t 之一）。配置通道需调用函数 ledc_channel_config()。

通道的配置与定时器设置类似，需向通道配置函数传递包括通道配置参数的结构体 ledc_channel_config_t 。

此时，通道会按照 ledc_channel_config_t 的配置开始运作，并在选定的 GPIO 上生成由定时器设置指定的频率和占空比的 PWM 信号。在通道运作过程中，可以随时通过调用函数 ledc_stop() 将其暂停。

通道开始运行、生成具有恒定占空比和频率的 PWM 信号之后，有几种方式可以改变该信号。驱动 LED 时，主要通过改变占空比来变化光线亮度。

以下两节介绍了如何使用软件和硬件改变占空比。如有需要，PWM 信号的频率也可更改，详见 改变 PWM 频率 一节。

调用函数 ledc_set_duty() 可以设置新的占空比。之后，调用函数 ledc_update_duty() 使新配置生效。要查看当前设置的占空比，可使用 _get_ 函数 ledc_get_duty()。

另外一种设置占空比和其他通道参数的方式是调用 通道配置 一节提到的函数 ledc_channel_config()。

传递给函数的占空比数值范围取决于选定的 duty_resolution，应为 0 至 (2 ** duty_resolution) - 1。例如，如选定的占空比分辨率为 10，则占空比的数值范围为 0 至 1023。此时分辨率为 ~0.1%。

LED PWM 控制器硬件可逐渐改变占空比的数值。要使用此功能，需用函数 ledc_fade_func_install() 使能渐变，之后用下列可用渐变函数之一配置：

ledc_set_fade_with_time()

ledc_set_fade_with_step()

ledc_set_fade()

最后用 ledc_fade_start() 开启渐变。

如不需要渐变和渐变中断，可用函数 ledc_fade_func_uninstall() 关闭。

LED PWM 控制器 API 有多种方式即时改变 PWM 频率：

通过调用函数 ledc_set_freq() 设置频率。可用函数 ledc_get_freq() 查看当前频率。

通过调用函数 ledc_bind_channel_timer() 将其他定时器绑定到该通道来改变频率和占空比分辨率。

通过调用函数 ledc_channel_config() 改变通道的定时器。

有一些较底层的定时器特定函数可用于更改 PWM 设置：

ledc_timer_set()

ledc_timer_rst()

ledc_timer_pause()

ledc_timer_resume()

前两个功能可通过函数 ledc_channel_config() 在后台运行，在定时器配置后启动。

配置 LED PWM 控制器通道时，可在 ledc_channel_config_t 中选取参数 ledc_intr_type_t ，在渐变完成时触发中断。

要注册处理程序来处理中断，可调用函数 ledc_isr_register()。

高速模式的优点是可平稳地改变定时器设置。也就是说，高速模式下如定时器设置改变，此变更会自动应用于定时器的下一次溢出中断。而更新低速定时器时，设置变更应由软件显式触发。LED PWM 驱动的设置将在硬件层面被修改，比如在调用函数 ledc_timer_config() 或 ledc_timer_set() 时。

更多关于速度模式的详细信息请参阅 ESP32 技术参考手册 > LED PWM 控制器 (LEDC) [PDF]。注意，该手册中提到的支持 SLOW_CLOCK 暂不适用于 LED PWM 驱动。

LED PWM 控制器主要用于驱动 LED。该控制器 PWM 占空比设置的分辨率范围较广。比如，PWM 频率为 5 kHz 时，占空比分辨率最大可为 13 位。这意味着占空比可为 0 至 100% 之间的任意值，分辨率为 ~0.012%（2 ** 13 = 8192 LED 亮度的离散电平）。然而，这些参数取决于为 LED PWM 控制器定时器计时的时钟信号，LED PWM 控制器为通道提供时钟（具体可参考 定时器配置 和 ESP32 技术参考手册 > LED PWM 计时器 (LEDC) [PDF]）。

LED PWM 控制器可用于生成频率较高的信号，足以为数码相机模组等其他设备提供时钟。此时，最大频率可为 40 MHz，占空比分辨率为 1 位。也就是说，占空比固定为 50%，无法调整。

LED PWM 控制器 API 会在设定的频率和占空比分辨率超过 LED PWM 控制器硬件范围时报错。例如，试图将频率设置为 20 MHz、占空比分辨率设置为 3 位时，串行端口监视器上会报告如下错误：

此时，占空比分辨率或频率必须降低。比如，将占空比分辨率设置为 2 会解决这一问题，让占空比设置为 25% 的倍数，即 25%、50% 或 75%。

如设置的频率和占空比分辨率低于所支持的最低值，LED PWM 驱动器也会反映并报告，如：

占空比分辨率通常用 ledc_timer_bit_t 设置，范围是 10 至 15 位。如需较低的占空比分辨率（上至 10，下至 1），可直接输入相应数值。

使用 LEDC 改变占空比和渐变控制的实例请参照 peripherals/ledc/ledc_fade。

使用 LEDC 基本实例请参照 peripherals/ledc/ledc_basic。

components/driver/include/driver/ledc.h

LEDC channel configuration Configure LEDC channel with the given channel/output gpio_num/interrupt/source timer/frequency(Hz)/LEDC duty resolution.

ESP_OK Success

ESP_ERR_INVALID_ARG Parameter error

ledc_conf: Pointer of LEDC channel configure struct

LEDC timer configuration Configure LEDC timer with the given source timer/frequency(Hz)/duty_resolution.

ESP_OK Success

ESP_ERR_INVALID_ARG Parameter error

ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current duty_resolution.

timer_conf: Pointer of LEDC timer configure struct

LEDC update channel parameters.

Call this function to activate the LEDC updated parameters. After ledc_set_duty, we need to call this function to update the settings.

ledc_set_duty, ledc_set_duty_with_hpoint and ledc_update_duty are not thread-safe, do not call these functions to control one LEDC channel in different tasks at the same time. A thread-safe version of API is ledc_set_duty_and_update

ESP_OK Success

ESP_ERR_INVALID_ARG Parameter error

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

Set LEDC output gpio.

ESP_OK Success

ESP_ERR_INVALID_ARG Parameter error

gpio_num: The LEDC output gpio

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

ledc_channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

LEDC stop. Disable LEDC output, and set idle level.

ESP_OK Success

ESP_ERR_INVALID_ARG Parameter error

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

idle_level: Set output idle level after LEDC stops.

LEDC set channel frequency (Hz)

ESP_OK Success

ESP_ERR_INVALID_ARG Parameter error

ESP_FAIL Can not find a proper pre-divider number base on the given frequency and the current duty_resolution.

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

timer_num: LEDC timer index (0-3), select from ledc_timer_t

freq_hz: Set the LEDC frequency

LEDC get channel frequency (Hz)

0 error

Others Current LEDC frequency

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

timer_num: LEDC timer index (0-3), select from ledc_timer_t

LEDC set duty and hpoint value Only after calling ledc_update_duty will the duty update.

ledc_set_duty, ledc_set_duty_with_hpoint and ledc_update_duty are not thread-safe, do not call these functions to control one LEDC channel in different tasks at the same time. A thread-safe version of API is ledc_set_duty_and_update

If a fade operation is running in progress on that channel, the driver would not allow it to be stopped. Other duty operations will have to wait until the fade operation has finished.

ESP_OK Success

ESP_ERR_INVALID_ARG Parameter error

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

duty: Set the LEDC duty, the range of duty setting is [0, (2**duty_resolution) - 1]

hpoint: Set the LEDC hpoint value(max: 0xfffff)

LEDC get hpoint value, the counter value when the output is set high level.

LEDC_ERR_VAL if parameter error

Others Current hpoint value of LEDC channel

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

LEDC set duty This function do not change the hpoint value of this channel. if needed, please call ledc_set_duty_with_hpoint. only after calling ledc_update_duty will the duty update.

ledc_set_duty, ledc_set_duty_with_hpoint and ledc_update_duty are not thread-safe, do not call these functions to control one LEDC channel in different tasks at the same time. A thread-safe version of API is ledc_set_duty_and_update.

If a fade operation is running in progress on that channel, the driver would not allow it to be stopped. Other duty operations will have to wait until the fade operation has finished.

ESP_OK Success

ESP_ERR_INVALID_ARG Parameter error

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

duty: Set the LEDC duty, the range of duty setting is [0, (2**duty_resolution) - 1]

LEDC get duty.

LEDC_ERR_DUTY if parameter error

Others Current LEDC duty

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

LEDC set gradient Set LEDC gradient, After the function calls the ledc_update_duty function, the function can take effect.

If a fade operation is running in progress on that channel, the driver would not allow it to be stopped. Other duty operations will have to wait until the fade operation has finished.

ESP_OK Success

ESP_ERR_INVALID_ARG Parameter error

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

duty: Set the start of the gradient duty, the range of duty setting is [0, (2**duty_resolution) - 1]

fade_direction: Set the direction of the gradient

step_num: Set the number of the gradient

duty_cycle_num: Set how many LEDC tick each time the gradient lasts

duty_scale: Set gradient change amplitude

Register LEDC interrupt handler, the handler is an ISR. The handler will be attached to the same CPU core that this function is running on.

ESP_OK Success

ESP_ERR_INVALID_ARG Function pointer error.

fn: Interrupt handler function.

arg: User-supplied argument passed to the handler function.

intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.

handle: Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.

Configure LEDC settings.

(-1) Parameter error

Other Current LEDC duty

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

timer_sel: Timer index (0-3), there are 4 timers in LEDC module

clock_divider: Timer clock divide value, the timer clock is divided from the selected clock source

duty_resolution: Resolution of duty setting in number of bits. The range of duty values is [0, (2**duty_resolution)]

clk_src: Select LEDC source clock.

Reset LEDC timer.

ESP_ERR_INVALID_ARG Parameter error

ESP_OK Success

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

timer_sel: LEDC timer index (0-3), select from ledc_timer_t

Pause LEDC timer counter.

ESP_ERR_INVALID_ARG Parameter error

ESP_OK Success

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

timer_sel: LEDC timer index (0-3), select from ledc_timer_t

Resume LEDC timer.

ESP_ERR_INVALID_ARG Parameter error

ESP_OK Success

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

timer_sel: LEDC timer index (0-3), select from ledc_timer_t

Bind LEDC channel with the selected timer.

ESP_ERR_INVALID_ARG Parameter error

ESP_OK Success

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

channel: LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

timer_sel: LEDC timer index (0-3), select from ledc_timer_t

Set LEDC fade function.

Call ledc_fade_func_install() once before calling this function. Call ledc_fade_start() after this to start fading.

ledc_set_fade_with_step, ledc_set_fade_with_time and ledc_fade_start are not thread-safe, do not call these functions to control one LEDC channel in different tasks at the same time. A thread-safe version of API is ledc_set_fade_step_and_start

If a fade operation is running in progress on that channel, the driver would not allow it to be stopped. Other duty operations will have to wait until the fade operation has finished.

ESP_ERR_INVALID_ARG Parameter error

ESP_OK Success

ESP_ERR_INVALID_STATE Fade function not installed.

ESP_FAIL Fade function init error

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. ,

channel: LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

target_duty: Target duty of fading [0, (2**duty_resolution) - 1]

scale: Controls the increase or decrease step scale.

cycle_num: increase or decrease the duty every cycle_num cycles

Set LEDC fade function, with a limited time.

Call ledc_fade_func_install() once before calling this function. Call ledc_fade_start() after this to start fading.

ledc_set_fade_with_step, ledc_set_fade_with_time and ledc_fade_start are not thread-safe, do not call these functions to control one LEDC channel in different tasks at the same time. A thread-safe version of API is ledc_set_fade_step_and_start

If a fade operation is running in progress on that channel, the driver would not allow it to be stopped. Other duty operations will have to wait until the fade operation has finished.

ESP_ERR_INVALID_ARG Parameter error

ESP_OK Success

ESP_ERR_INVALID_STATE Fade function not installed.

ESP_FAIL Fade function init error

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode. ,

channel: LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

target_duty: Target duty of fading [0, (2**duty_resolution) - 1]

max_fade_time_ms: The maximum time of the fading ( ms ).

Install LEDC fade function. This function will occupy interrupt of LEDC module.

ESP_OK Success

ESP_ERR_INVALID_STATE Fade function already installed.

intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.

Uninstall LEDC fade function.

Start LEDC fading.

Call ledc_fade_func_install() once before calling this function. Call this API right after ledc_set_fade_with_time or ledc_set_fade_with_step before to start fading.

If a fade operation is running in progress on that channel, the driver would not allow it to be stopped. Other duty operations will have to wait until the fade operation has finished.

ESP_OK Success

ESP_ERR_INVALID_STATE Fade function not installed.

ESP_ERR_INVALID_ARG Parameter error.

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

channel: LEDC channel number

fade_mode: Whether to block until fading done.

A thread-safe API to set duty for LEDC channel and return when duty updated.

If a fade operation is running in progress on that channel, the driver would not allow it to be stopped. Other duty operations will have to wait until the fade operation has finished.

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

channel: LEDC channel (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

duty: Set the LEDC duty, the range of duty setting is [0, (2**duty_resolution) - 1]

hpoint: Set the LEDC hpoint value(max: 0xfffff)

A thread-safe API to set and start LEDC fade function, with a limited time.

Call ledc_fade_func_install() once, before calling this function.

If a fade operation is running in progress on that channel, the driver would not allow it to be stopped. Other duty operations will have to wait until the fade operation has finished.

ESP_ERR_INVALID_ARG Parameter error

ESP_OK Success

ESP_ERR_INVALID_STATE Fade function not installed.

ESP_FAIL Fade function init error

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

channel: LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

target_duty: Target duty of fading [0, (2**duty_resolution) - 1]

max_fade_time_ms: The maximum time of the fading ( ms ).

fade_mode: choose blocking or non-blocking mode

A thread-safe API to set and start LEDC fade function.

Call ledc_fade_func_install() once before calling this function.

If a fade operation is running in progress on that channel, the driver would not allow it to be stopped. Other duty operations will have to wait until the fade operation has finished.

ESP_ERR_INVALID_ARG Parameter error

ESP_OK Success

ESP_ERR_INVALID_STATE Fade function not installed.

ESP_FAIL Fade function init error

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

channel: LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

target_duty: Target duty of fading [0, (2**duty_resolution) - 1]

scale: Controls the increase or decrease step scale.

cycle_num: increase or decrease the duty every cycle_num cycles

fade_mode: choose blocking or non-blocking mode

LEDC callback registration function.

The callback is called from an ISR, it must never attempt to block, and any FreeRTOS API called must be ISR capable.

ESP_ERR_INVALID_ARG Parameter error

ESP_OK Success

ESP_ERR_INVALID_STATE Fade function not installed.

ESP_FAIL Fade function init error

speed_mode: Select the LEDC channel group with specified speed mode. Note that not all targets support high speed mode.

channel: LEDC channel index (0 - LEDC_CHANNEL_MAX-1), select from ledc_channel_t

cbs: Group of LEDC callback functions

user_arg: user registered data for the callback function

LEDC callback parameter.

Public Members

Event name

Speed mode of the LEDC channel group

LEDC channel (0 - LEDC_CHANNEL_MAX-1)

LEDC current duty of the channel, the range of duty is [0, (2**duty_resolution) - 1]

Group of supported LEDC callbacks.

The callbacks are all running under ISR environment

Public Members

LEDC fade_end callback function

Type of LEDC event callback.

param: LEDC callback parameter

user_arg: User registered data

LEDC callback event type.

Values:

LEDC fade end event

components/hal/include/hal/ledc_types.h

Configuration parameters of LEDC channel for ledc_channel_config function.

Public Members

the LEDC output gpio_num, if you want to use gpio16, gpio_num = 16

LEDC speed speed_mode, high-speed mode or low-speed mode

LEDC channel (0 - 7)

configure interrupt, Fade interrupt enable or Fade interrupt disable

Select the timer source of channel (0 - 3)

LEDC channel duty, the range of duty setting is [0, (2**duty_resolution)]

LEDC channel hpoint value, the max value is 0xfffff

Enable (1) or disable (0) gpio output invert

LEDC flags

Configuration parameters of LEDC Timer timer for ledc_timer_config function.

Public Members

LEDC speed speed_mode, high-speed mode or low-speed mode

LEDC channel duty resolution

Deprecated in ESP-IDF 3.0. This is an alias to ‘duty_resolution’ for backward compatibility with ESP-IDF 2.1

The timer source of channel (0 - 3)

LEDC timer frequency (Hz)

Configure LEDC source clock. For low speed channels and high speed channels, you can specify the source clock using LEDC_USE_REF_TICK, LEDC_USE_APB_CLK or LEDC_AUTO_CLK. For low speed channels, you can also specify the source clock using LEDC_USE_RTC8M_CLK, in this case, all low speed channel’s source clock must be RTC8M_CLK

Values:

LEDC high speed speed_mode

LEDC low speed speed_mode

LEDC speed limit

Values:

Disable LEDC interrupt

Enable LEDC interrupt

Values:

LEDC duty decrease direction

LEDC duty increase direction

Values:

LEDC low speed timer clock source is 8MHz RTC clock

LEDC low speed timer clock source is 80MHz APB clock

Values:

The driver will automatically select the source clock(REF_TICK or APB) based on the giving resolution and duty parameter when init the timer

LEDC timer select REF_TICK clock as source clock

LEDC timer select APB clock as source clock

LEDC timer select RTC8M_CLK as source clock. Only for low speed channels and this parameter must be the same for all low speed channels

Values:

LEDC timer clock divided from reference tick (1Mhz)

LEDC timer clock divided from APB clock (80Mhz)

Values:

LEDC timer 0

LEDC timer 1

LEDC timer 2

LEDC timer 3

Values:

LEDC channel 0

LEDC channel 1

LEDC channel 2

LEDC channel 3

LEDC channel 4

LEDC channel 5

LEDC channel 6

LEDC channel 7

Values:

LEDC PWM duty resolution of 1 bits

LEDC PWM duty resolution of 2 bits

LEDC PWM duty resolution of 3 bits

LEDC PWM duty resolution of 4 bits

LEDC PWM duty resolution of 5 bits

LEDC PWM duty resolution of 6 bits

LEDC PWM duty resolution of 7 bits

LEDC PWM duty resolution of 8 bits

LEDC PWM duty resolution of 9 bits

LEDC PWM duty resolution of 10 bits

LEDC PWM duty resolution of 11 bits

LEDC PWM duty resolution of 12 bits

LEDC PWM duty resolution of 13 bits

LEDC PWM duty resolution of 14 bits

LEDC PWM duty resolution of 15 bits

LEDC PWM duty resolution of 16 bits

LEDC PWM duty resolution of 17 bits

LEDC PWM duty resolution of 18 bits

LEDC PWM duty resolution of 19 bits

LEDC PWM duty resolution of 20 bits

Values:

LEDC fade function will return immediately

LEDC fade function will block until fading to the target duty